Inside Macintosh: QuickDraw GX Graphics /

Chapter 3 - Geometric Styles / Using Geometric Styles

Adding Caps to a Shape

To add a cap shape to the ends of another shape's contours, you must create a cap record structure. The cap structure has three fields: one for the start cap shape, one for the end cap shape, and one for the cap attributes.

Listing 3-9 shows how to create a cap structure with an arrow head for the start cap, an arrow tail for the end cap, and no cap attributes.

Listing 3-9 Creating an arrow

void CreateArrow(void)
{
   gxShape aCurve, arrowHead, arrowTail;

   static gxCurve curveGeometry = {ff(25),  ff(125), 
                                   ff(100), 0, 
                                   ff(225), ff(125)};
   
   static long arrowHeadPolygonGeometry[] = {4, /* # of points */
                                             -ff(3), 0,
                                             0, fixed1, 
                                             fixed1, 0, 
                                             0, -fixed1};
                                      
   static long arrowTailPolygonGeometry[] = {5, /* # of points */
                                             -fixed1, 0, 
                                             0, fixed1, 
                                             ff(2), fixed1, 
                                             ff(2), -fixed1, 
                                             0, -fixed1};
   gxCapRecord theCapRecord;


   aCurve = GXNewCurve (&curveGeometry);
   
   arrowHead = NewPolygon((gxPolygon *) 
                           &arrowHeadPolygonGeometry);
   arrowTail = NewPolygon((gxPolygon *) 
                           &arrowTailPolygonGeometry);

   theCapRecord.startCap = arrowHead;
   theCapRecord.endCap = arrowTail;
   theCapRecord.attributes = gxNoAttributes;

   GXSetShapeCap(aCurve, &theCapRecord);
   
   GXDisposeShape(arrowHead);
   GXDisposeShape(arrowTail);
   
   GXSetShapePen(aCurve, ff(10));
   
   GXDrawShape(aCurve);
   
   GXDisposeShape(aCurve);
}

This sample function creates two polygon shapes: one for the arrow head and one for the arrow tail. It then creates a cap structure that contains references to the two shape objects and an attributes field with no attributes set.

The sample function then calls the GXSetShapeCap function, which sets the cap property of the curve shape's style object. (Remember, it makes a copy of this style object if the style is shared amongst multiple shapes.)

When the GXSetShapeCap function copies the start cap and the end cap from the cap record to the curve's style object, it does not simply copy references to the arrow head polygon and the arrow tail polygon. Instead, it makes copies of those shapes and includes the copies in the cap property of the curve's style object. After setting the curve shape's caps, you may subsequently make changes to the arrow head and arrow tail shapes without affecting the start cap or end cap of the curve.

Note

Actually, the GXSetShapeCap function does not copy the entire start cap shape or end cap shape. Instead, it copies only the geometric information of the start and end cap shapes. For this reason, you must provide start cap shapes and end cap shapes in their primitive forms.

After the CreateArrow sample function sets the caps of the curve shape, it disposes of the arrow head and arrow tail polygons. At this point, the owner count of these shapes becomes 0 (since the curve's style does not actually reference these shapes), and the memory used by the two polygon shapes is freed.

Note

In the same way that the GXSetShapeCap function copies geometry information from the start and end cap shapes into a style's cap property, the GXGetShapeCap function creates new shape objects and copies the geometry information from a style's cap property into the new shapes. If you use the GXGetShapeCap function to find the caps of a shape and alter those caps, you must use the GXSetShapeCap function to copy your changes back into the shape's caps.

Figure 3-53 shows the result of the CreateArrow sample function.

Figure 3-53 An arrow

Notice that QuickDraw GX rotates the start cap and the end cap to match the slope of the curve's contour, and scales them by the width of the pen. You can suppress the rotation by setting the level start-cap attribute and the level end-cap attribute.

The sections "The Cap Structure" on page 3-99 and "Cap Attributes" on page 3-101 describe the cap structure and the cap attributes in more detail, and the section "Getting and Setting Caps" beginning on page 3-123 describes the functions you can use to manipulate caps.